<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Using Translation Adapters - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.translate.using.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.translate.using.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.translate.adapter.html">Adapters for Zend_Translate</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.translate.html">Zend_Translate</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.translate.sourcecreation.html">Creating source files</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.translate.using" class="section"><div class="info"><h1 class="title">Using Translation Adapters</h1></div>
    

    <p class="para">
        The next step is to use the adapter within your code.
    </p>

    <div class="example" id="zend.translate.using.example1"><div class="info"><p><b>Example #1 Example of single-language PHP code</b></p></div>
        

        <pre class="programlisting brush: php">
print &quot;Example\n&quot;;
print &quot;=======\n&quot;;
print &quot;Here is line one\n&quot;;
print &quot;Today is the &quot; . date(&quot;d.m.Y&quot;) . &quot;\n&quot;;
print &quot;\n&quot;;
print &quot;Here is line two\n&quot;;
</pre>

    </div>

    <p class="para">
        The example above shows some output with no support for translation.
        You probably write your code in your native language.
        Generally you need to translate not only the output,
        but also error and log messages.
    </p>

    <p class="para">
        The next step is to integrate <span class="classname">Zend_Translate</span> into your existing code.
        Of course it is much easier if you had already written your code with
        translation in mind, than changing your code afterwards.
    </p>

    <div class="example" id="zend.translate.using.example2"><div class="info"><p><b>Example #2 Example of multi-lingual PHP code</b></p></div>
        

        <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/my/path/source-de.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;de&#039;
    )
);
$translate-&gt;addTranslation(
    array(
        &#039;content&#039; =&gt; &#039;/path/to/translation/fr-source.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;fr&#039;
    )
);

print $translate-&gt;_(&quot;Example&quot;) . &quot;\n&quot;;
print &quot;=======\n&quot;;
print $translate-&gt;_(&quot;Here is line one&quot;) . &quot;\n&quot;;
printf($translate-&gt;_(&quot;Today is the %1\$s&quot;) . &quot;\n&quot;, date(&#039;d.m.Y&#039;));
print &quot;\n&quot;;

$translate-&gt;setLocale(&#039;fr&#039;);
print $translate-&gt;_(&quot;Here is line two&quot;) . &quot;\n&quot;;
</pre>

    </div>

    <p class="para">
        Now let&#039;s take a deeper look into what has been done and how to
        integrate <span class="classname">Zend_Translate</span> into your own code.
    </p>

    <p class="para">
        Create a new <span class="classname">Zend_Translate</span> object and define the base adapter:
    </p>

    <pre class="programlisting brush: php">
$translate = new Zend_Translate
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/translation/source-de.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;de&#039;
    )
);
</pre>


    <p class="para">
        In this example we chose the
        <em class="emphasis">Gettext Adapter</em>.
        We place our file <em class="emphasis">source-de.mo</em>
        into the directory <em class="emphasis">/path/to/translation</em>.
        The gettext file will have German translation included,
        and we also added another language source for French.
    </p>

    <p class="para">
        The next step is to wrap all strings which are to be translated.
        The simplest approach is to have only simple strings or sentences
        like this:
    </p>

    <pre class="programlisting brush: php">
print $translate-&gt;_(&quot;Example&quot;) . &quot;\n&quot;;
print &quot;=======\n&quot;;
print $translate-&gt;_(&quot;Here is line one&quot;) . &quot;\n&quot;;
</pre>


    <p class="para">
        Some strings do not needed to be translated.
        The separating line is always a separating line,
        even in other languages.
    </p>

    <p class="para">
        Having data values integrated into a translation string is also
        supported through the use of embedded parameters.
    </p>

    <pre class="programlisting brush: php">
printf($translate-&gt;_(&quot;Today is the %1\$s&quot;) . &quot;\n&quot;, date(&quot;d.m.Y&quot;));
</pre>


    <p class="para">
        Instead of  <span class="methodname">print()</span>, use the  <span class="methodname">printf()</span>
        function and replace all parameters with <em class="emphasis">%1\$s</em> parts.
        The first is <em class="emphasis">%1\$s</em>, the second is <em class="emphasis">%2\$s</em>,
        and so on. This way a translation can be done without knowing
        the exact value. In our example, the date is always the actual day,
        but the string can be translated without the knowledge of the actual
        day.
    </p>

    <p class="para">
        Each string is identified in the translation storage by a message ID.
        You can use message IDs instead of strings in your code, like this:
    </p>

    <pre class="programlisting brush: php">
print $translate-&gt;_(1) . &quot;\n&quot;;
print &quot;=======\n&quot;;
print $translate-&gt;_(2) . &quot;\n&quot;;
</pre>


    <p class="para">
        But doing this has several disadvantages:
    </p>

    <p class="para">
        You can not see what your code should output just by viewing your code.
    </p>

    <p class="para">
        Also you will have problems if some strings are not translated.
        You must always keep in mind how translation works.
        First <span class="classname">Zend_Translate</span> checks whether the specified language has a
        translation for the given message ID or string.
        If no translation string has been found it refers to the next lower
        level language as defined within <span class="classname">Zend_Locale</span>.
        So &quot;<em class="emphasis">de_AT</em>&quot; becomes
        &quot;<em class="emphasis">de</em>&quot; only.
        If there is no translation found for
        &quot;<em class="emphasis">de</em>&quot; either,
        then the original message is returned.
        This way you always have an output, even in case the message translation
        does not exist in your message storage.
        <span class="classname">Zend_Translate</span> never throws an error or exception when translating
        strings.
    </p>

    <div class="section" id="zend.translate.using.structure"><div class="info"><h1 class="title">Translation Source Structures</h1></div>
        

        <p class="para">
            Your next step is to create the translation sources for the
            languages you want to translate.
            Every adapter is created its own way as described here,
            but there are common features applicable for all adapters.
        </p>

        <p class="para">
            You have to decide where to store your translation source files.
            Using <span class="classname">Zend_Translate</span> you are not restricted in any way.
            The following structures are preferable:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    Single structured source
                </p>

                <pre class="programlisting brush: txt">
/application/
/languages/
/languages/lang.en
/languages/lang.de
/library/
</pre>


                <p class="para">
                    Positive: all source files for every languages are stored
                    in one directory. No splitting of related files.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Language structured source
                </p>

                <pre class="programlisting brush: txt">
/application/
/languages/
/languages/en/
/languages/en/first.en
/languages/en/second.en
/languages/de/
/languages/de/first.de
/languages/de/second.de
/library
</pre>


                <p class="para">
                    Positive: Every language is stored in their own directories.
                    Easy translation, as every language team has to translate
                    only one directory. Also the usage of multiple files is transparent.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Application structured source
                </p>

                <pre class="programlisting brush: txt">
/application/
/application/languages/
/application/languages/first.en
/application/languages/first.de
/application/languages/second.en
/application/languages/second.de
/library/
</pre>


                <p class="para">
                    Positive: all source files for every language are stored
                    in one directory. No splitting of related files.
                </p>

                <p class="para">
                    Negative: having multiple files for the same language can be
                    problematic.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Gettext structured source
                </p>

                <pre class="programlisting brush: txt">
/application/
/languages/
/languages/de/
/languages/de/LC_MESSAGES/
/languages/de/LC_MESSAGES/first.mo
/languages/de/LC_MESSAGES/second.mo
/languages/en/
/languages/en/LC_MESSAGES/
/languages/en/LC_MESSAGES/first.mo
/languages/en/LC_MESSAGES/second.mo
/library/
</pre>


                <p class="para">
                    Positive: existing gettext sources can be used without changing
                    structure.
                </p>

                <p class="para">
                    Negative: having sub-sub directories may be confusing
                    for people who have not used gettext before.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                   File structured source
                </p>

                <pre class="programlisting brush: txt">
/application/
/application/models/
/application/models/MyModel.php
/application/models/MyModel.de
/application/models/MyModel.en
/application/controllers/
/application/controllers/MyController.php
/application/controllers/MyController.de
/application/controllers/MyController.en
/library/
</pre>


                <p class="para">
                    Positive: translation files are localted near their source.
                </p>

                <p class="para">
                    Negative: too many and also small translation files result in
                    being tedious to translate.
                    Also every file has to be added as translation source.
                </p>
            </li>
        </ul>

        <p class="para">
            Single structured and language structured source files are most
            usable for <span class="classname">Zend_Translate</span>.
        </p>

        <p class="para">
            So now, that we know which structure we want to have,
            we should create our translation source files.
        </p>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.translate.adapter.html">Adapters for Zend_Translate</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.translate.html">Zend_Translate</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.translate.sourcecreation.html">Creating source files</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.translate.html">Zend_Translate</a></li>
  <li><a href="zend.translate.introduction.html">Introduction</a></li>
  <li><a href="zend.translate.adapter.html">Adapters for Zend_Translate</a></li>
  <li class="active"><a href="zend.translate.using.html">Using Translation Adapters</a></li>
  <li><a href="zend.translate.sourcecreation.html">Creating source files</a></li>
  <li><a href="zend.translate.additional.html">Additional features for translation</a></li>
  <li><a href="zend.translate.plurals.html">Plural notations for Translation</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>